Webhook Support

Outter supports webhooks to deliver results and events to your application in real-time, enabling asynchronous workflows and push-based notifications. Instead of polling for results or keeping a connection open, you can set up a webhook and have Outter call your endpoint when an AI task is completed or when certain events occur.

Configuring a Webhook for Async Responses

For long-running requests or when you want to decouple the response handling, you can ask Outter to send the result to a webhook URL. There are two main steps:

1. Provide a Webhook URL – You can include your webhook callback URL in the API request. Most Outter endpoints accept a field like "webhookUrl" (or similar) in the request JSON. Alternatively, you might configure a default webhook URL in your Outter dashboard for certain event types.
2. Handle the Immediate Response – When you send a request with a webhook, Outter will typically immediately return an acknowledgment with a request ID or status, while it continues processing in the background. For example, it might return { "status": "processing", "requestId": "abc123" }.
3. Receive the Webhook – Once processing is complete, Outter will make an HTTP POST to the URL you provided. The POST body will contain the result (and usually the requestId or some identifier to correlate it with your original request).

Example Workflow

Using a webhook for a content generation request:

Client Request: POST /api/ai/content/generate

{
    "prompt": "Long text to summarize...",
    "webhookUrl": "<https://yourapp.com/outter-webhook>"
    }

Immidiate Response

Response

{
    "status": "processing",
    "requestId": "req-23b27463"
    }

Outter Webhook Callback: Outter sends an HTTP POST to https://yourapp.com/outter-webhook with JSON

    {
      "requestId": "req-23b27463",
      "result": "Here is the summarized text ...",
      "model": "gpt-4",
      "usage": { "totalTokens": 500 }
    }
    

Your webhook endpoint should verify the request (see Security and Verification Secrion Below) and then handle the result (e.g., save it to a database or forward it to the front-end via a WebSocket).

Setting the webhookUrl in the request is straightforward as shown. On your server side, you need to implement the /outter-webhook endpoint to accept POST requests. For example, in Express (Node.js) you might have:

app.post('/outter-webhook', (req, res) => {
  const result = req.body.result;
  const reqId = req.body.requestId;
  // Verify signature to ensure this is from Outter
  // Process the result (e.g., store or send to client)
  console.log(`Received result for ${reqId}: ${result}`);
  res.sendStatus(200); // Acknowledge receipt to Outter
});